<!DOCTYPE HTML>
<html lang="en">
<head>
<title>WinSet - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The WinSet command makes a variety of changes to the specified window, such as &quot;always on top&quot; and transparency." />
<meta name="ahk:equiv-v2" content="commands/Win.htm" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>WinSet</h1>

<p>Makes a variety of changes to the specified window, such as &quot;always on top&quot; and transparency.</p>
<pre class="Syntax"><span class="func">WinSet</span>, <a href="#SubCommands">SubCommand</a>, Value <span class="optional">, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>

<h2>Parameters</h2>
<dl>
  <dt>SubCommand, Value</dt>
  <dd>These are dependent upon each other and their usage is described <a href="#SubCommands">below</a>.</dd>

  <dt>WinTitle</dt>
  <dd>A window title or other criteria identifying the target window. See <a href="../misc/WinTitle.htm">WinTitle</a>.</dd>

  <dt>WinText</dt>
  <dd>If present, this parameter must be a substring from a single text element of the target window (as revealed by the included Window Spy utility). Hidden text elements are detected if <a href="DetectHiddenText.htm">DetectHiddenText</a> is ON.</dd>

  <dt>ExcludeTitle</dt>
  <dd>Windows whose titles include this value will not be considered.</dd>

  <dt>ExcludeText</dt>
  <dd>Windows whose text include this value will not be considered.</dd>
</dl>

<h2 id="SubCommands">Sub-commands</h2>
<p>For <em>SubCommand</em>, specify one of the following:</p>
<ul>
  <li><a href="#AlwaysOnTop">AlwaysOnTop</a>: Makes a window stay on top of all other windows.</li>
  <li><a href="#Bottom">Bottom</a>: Sends a window to the bottom of stack; that is, beneath all other windows.</li>
  <li><a href="#Top">Top</a>: Brings a window to the top of the stack without explicitly activating it.</li>
  <li><a href="#Disable">Disable</a>: Disables a window.</li>
  <li><a href="#Enable">Enable</a>: Enables a window.</li>
  <li><a href="#Redraw">Redraw</a>: Redraws a window.</li>
  <li><a href="#Style">Style</a>: Changes the style of a window.</li>
  <li><a href="#ExStyle">ExStyle</a>: Changes the extended style of a window.</li>
  <li><a href="#Region">Region</a>: Changes the shape of a window to be the specified rectangle, ellipse, or polygon.</li>
  <li><a href="#Transparent">Transparent</a>: Makes a window semi-transparent.</li>
  <li><a href="#TransColor">TransColor</a>: Makes all pixels of the chosen color invisible inside the target window.</li>
</ul>

<h3 id="AlwaysOnTop">AlwaysOnTop</h3>
<p>Makes a window stay on top of all other windows.</p>
<pre class="Syntax"><span class="func">WinSet</span>, AlwaysOnTop <span class="optional">, OnOffToggle, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>For <em>OnOffToggle</em>, specify <code>On</code> turn on the setting, <code>Off</code> to turn it off, or <code>Toggle</code> to set it to the opposite of its current state. If <em>OnOffToggle</em> is blank or omitted, it defaults to <code>Toggle</code>. The word Topmost can be used in place of AlwaysOnTop.</p>
<p><span class="ver">[v1.1.30+]:</span> The decimal values 1, 0 and -1 may be used in place of On, Off and Toggle, respectively.</p>

<h3 id="Bottom">Bottom</h3>
<p>Sends a window to the bottom of stack; that is, beneath all other windows.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Bottom <span class="optional">,, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>The effect is similar to pressing <kbd>Alt</kbd>+<kbd>Esc</kbd>.</p>

<h3 id="Top">Top</h3>
<p>Brings a window to the top of the stack without explicitly <a href="WinActivate.htm">activating</a> it.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Top <span class="optional">,, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>However, the system default settings will probably cause it to activate in most cases. In addition, this sub-command may have no effect due to the operating system's protection against applications that try to steal focus from the user (it may depend on factors such as what type of window is currently active and what the user is currently doing). One possible work-around is to make the window briefly <a href="#AlwaysOnTop">AlwaysOnTop</a>, then turn off AlwaysOnTop.</p>

<h3 id="Disable">Disable</h3>
<p>Disables a window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Disable <span class="optional">,, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>When a window is disabled, the user cannot move it or interact with its controls. In addition, disabled windows are omitted from the alt-tab list.</p>

<h3 id="Enable">Enable</h3>
<p>Enables a window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Enable <span class="optional">,, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>

<h3 id="Redraw">Redraw</h3>
<p>Redraws a window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Redraw <span class="optional">,, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>This sub-command attempts to update the appearance/contents of a window by informing the OS that the window's rectangle needs to be redrawn. If this approach does not work for a particular window, try <a href="WinMove.htm">WinMove</a>. If that does not work, try <a href="WinHide.htm">WinHide</a> in combination with <a href="WinShow.htm">WinShow</a>.</p>

<h3 id="Style">Style</h3>
<p>Changes the style of a window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Style, N <span class="optional">, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>If the first character of <em>N</em> is a plus or minus sign, the style(s) in <em>N</em> are added or removed, respectively. If the first character is a caret (^), the style(s) in N are each toggled to the opposite state. If the first character is a digit, the window's style is overwritten completely; that is, it becomes <em>N</em>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 upon failure and 0 upon success. Failure occurs if the target window is not found or the style is not allowed to be applied.</p>
<p>After applying certain style changes to a visible window, it might be necessary to redraw the window using the <a href="#Redraw">Redraw</a> sub-command above. Finally, the <a href="../misc/Styles.htm">styles table</a> lists some of the common style numbers. For example:</p>
<pre>WinSet, Style, -0xC00000, A  <em>; Remove the active window's title bar (WS_CAPTION).</em></pre>

<h3 id="ExStyle">ExStyle</h3>
<p>Changes the extended style of a window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, ExStyle, N <span class="optional">, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>See the <a href="#Style">Style</a> sub-command for details. For example:</p>
<pre>WinSet, ExStyle, ^0x80, <i>WinTitle</i> <em>; Toggle the WS_EX_TOOLWINDOW attribute, which removes/adds the window from the alt-tab list.</em></pre>

<div id="region">
  <h3 id="Region">Region</h3>
</div>
<p>Changes the shape of a window to be the specified rectangle, ellipse, or polygon.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Region <span class="optional">, Options, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>If the <em>Options</em> parameter is blank or omitted, the window is restored to its original/default display area. Otherwise, one or more of the following options can be specified, each separated from the others with space(s):</p>
<p><strong>Wn</strong>: Width of rectangle or ellipse. For example: <code>w200</code>.</p>
<p><strong>Hn</strong>: Height of rectangle or ellipse. For example: <code>h200</code>.</p>
<p><strong>X-Y</strong>: Each of these is a pair of X/Y coordinates. For example, <code>200-0</code> would use 200 for the X coordinate and 0 for the Y.</p>
<p><strong>E</strong>: Makes the region an ellipse rather than a rectangle. This option is valid only when <strong>W</strong> and <strong>H</strong> are present.</p>
<p><strong>R[w-h]</strong>: Makes the region a rectangle with rounded corners. For example, <code>R30-30</code> would use a 30x30 ellipse for each corner. If <strong>w-h</strong> is omitted, 30-30 is used. <strong>R</strong> is valid only when <strong>W</strong> and <strong>H</strong> are present.</p>
<p><strong>Rectangle or ellipse</strong>: If the <strong>W</strong> and <strong>H</strong> options are present, the new display area will be a rectangle whose upper left corner is specified by the first (and only) pair of <strong>X-Y</strong> coordinates. However, if the <strong>E</strong> option is also present, the new display area will be an ellipse rather than a rectangle. For example: <code>WinSet, Region, 50-0 W200 H250 E, WinTitle</code>.</p>
<p><strong>Polygon</strong>: When the <strong>W</strong> and <strong>H</strong> options are absent, the new display area will be a polygon determined by multiple pairs of <strong>X-Y</strong> coordinates (each pair of coordinates is a point inside the window relative to its upper left corner). For example, if three pairs of coordinates are specified, the new display area will be a triangle in most cases. The order of the coordinate pairs with respect to each other is sometimes important. In addition, the word <strong>Wind</strong> maybe be present in <em>Options</em> to use the winding method instead of the alternating method to determine the polygon's region.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 upon failure and 0 upon success. Failure occurs when: 1) the target window does not exist; 2) one or more <em>Options</em> are invalid; 3) more than 2000 pairs of coordinates were specified; or 4) the specified region is invalid or could not be applied to the target window.</p>
<p>See <a href="#ExRegion">example #5</a> and <a href="#ExRegionAdvanced">example #6</a> at the bottom of this page for how to use this sub-command.</p>

<div id="trans">
  <h3 id="Transparent">Transparent</h3>
</div>
<p>Makes a window semi-transparent.</p>
<pre class="Syntax"><span class="func">WinSet</span>, Transparent <span class="optional">, N, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>Specify for <em>N</em> a number between 0 and 255 to indicate the degree of transparency: 0 makes the window invisible while 255 makes it opaque.</p>
<p>The word <code>Off</code> may be specified to completely turn off transparency for a window. This is functionally identical to <code>WinSet, <a href="#TransColor">TransColor</a>, Off, <i>WinTitle</i></code>. Specifying <code>Off</code> is different than specifying 255 because it may improve performance and reduce usage of system resources.</p>
<p>For example, to make the task bar transparent, use <code>WinSet, Transparent, 150, ahk_class Shell_TrayWnd</code>. Similarly, to make the classic Start Menu transparent, see <a href="#ExTransStartMenu">example #3</a>. To make the Start Menu's submenus transparent, also include the script from <a href="#ExTransMenu">example #4</a>.</p>
<p>Setting the transparency level to 255 before using <code>Off</code> might avoid window redrawing problems such as a black background. If the window still fails to be redrawn correctly, see <a href="#Redraw">Redraw</a> for a possible workaround.</p>
<p><span class="ver">[v1.1.24.05+]</span>: This sub-command also works with a window that lacks a caption (title bar) and lacks the <a href="#AlwaysOnTop">always-on-top</a> property.</p>

<h3 id="TransColor">TransColor</h3>
<p>Makes all pixels of the chosen color invisible inside the target window.</p>
<pre class="Syntax"><span class="func">WinSet</span>, TransColor, Color <span class="optional">, WinTitle, WinText, ExcludeTitle, ExcludeText</span></pre>
<p>This allows the contents of the window behind it to show through. If the user clicks on an invisible pixel, the click will &quot;fall through&quot; to the window behind it. Specify for <em>Color</em> a color name or RGB value (see the <a href="Progress.htm#colors">color chart</a> for guidance, or use <a href="PixelGetColor.htm">PixelGetColor</a> in its RGB mode). To additionally make the visible part of the window partially transparent, append a space (not a comma) followed by the transparency level (0-255). For example: <code>WinSet, TransColor, EEAA99 150, <i>WinTitle</i></code>.</p>
<p>The word <code>Off</code> may be specified to completely turn off transparency for a window. This is functionally identical to <code>WinSet, <a href="#Transparent">Transparent</a>, Off, <i>WinTitle</i></code>. Specifying <code>Off</code> is different than specifying 255 because it may improve performance and reduce usage of system resources.</p>
<p>TransColor is often used to create on-screen displays and other visual effects. There is an example of an on-screen display <a href="Gui.htm#OSD">at the bottom of the Gui page</a>.</p>
<p>Setting the transparency level to 255 before using <code>Off</code> might avoid window redrawing problems such as a black background. If the window still fails to be redrawn correctly, see <a href="#Redraw">Redraw</a> for a possible workaround.</p>
<p>To change a window's existing TransColor, it may be necessary to turn off transparency before making the change.</p>
<p><span class="ver">[v1.1.24.05+]</span>: This sub-command also works with a window that lacks a caption (title bar) and lacks the <a href="#AlwaysOnTop">always-on-top</a> property.</p>

<h2>Remarks</h2>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is not changed by this command except where indicated above.</p>
<p>Although transparency is supported on Windows 2000/XP or later, retrieving the current transparency settings of a window is possible only on Windows XP or later (via <a href="WinGet.htm">WinGet</a>).</p>
<p>A script's <a href="SplashTextOn.htm">SplashText</a> window can be made non-AlwaysOnTop via:</p>
<pre>WinSet, AlwaysOnTop, Off, My Splash Window Title</pre>
<p>Window titles and text are case sensitive. Hidden windows are not detected unless <a href="DetectHiddenWindows.htm">DetectHiddenWindows</a> has been turned on.</p>

<h2>Related</h2>
<p><a href="WinGet.htm">WinGet</a>, <a href="WinHide.htm">WinHide</a>, <a href="WinSetTitle.htm">WinSetTitle</a>, <a href="WinMove.htm">WinMove</a>, <a href="WinActivate.htm">WinActivate</a>, <a href="Control.htm">Control</a></p>

<h2>Examples</h2>

<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>WinSet, Transparent, 200, Untitled - Notepad <em>; Make the window a little bit transparent.</em>
WinSet, TransColor, White, Untitled - Notepad <em>; Make all white pixels invisible.</em>
WinSet, AlwaysOnTop, Toggle, Calculator <em>; Toggle the always-on-top status of Calculator.</em></pre>
</div>

<div class="ex" id="ExTransHotkey">
<p><a href="#ExTransHotkey">#2</a>: Here are some hotkeys that demonstrate the effects of the sub-commands <a href="#Transparent">Transparent</a> and <a href="#TransColor">TransColor</a>. NOTE: If you press one of the hotkeys while the mouse cursor is hovering over a pixel that is invisible as a result of TransColor, the window visible beneath that pixel will be acted upon instead! Also, <kbd>Win</kbd>+<kbd>G</kbd> will have an effect only on Windows XP or later because retrieval of transparency settings is not supported by Windows 2000:</p>
<pre>#t::  <em>; Press Win+T to make the color under the mouse cursor invisible.</em>
MouseGetPos, MouseX, MouseY, MouseWin
PixelGetColor, MouseRGB, %MouseX%, %MouseY%, RGB
<em>; It seems necessary to turn off any existing transparency first:</em>
WinSet, TransColor, Off, ahk_id %MouseWin%
WinSet, TransColor, %MouseRGB% 220, ahk_id %MouseWin%
return

#o::  <em>; Press Win+O to turn off transparency for the window under the mouse.</em>
MouseGetPos,,, MouseWin
WinSet, TransColor, Off, ahk_id %MouseWin%
return

#g::  <em>; Press Win+G to show the current settings of the window under the mouse.</em>
MouseGetPos,,, MouseWin
WinGet, Transparent, Transparent, ahk_id %MouseWin%
WinGet, TransColor, TransColor, ahk_id %MouseWin%
ToolTip Translucency:`t%Transparent%`nTransColor:`t%TransColor%
return</pre>
</div>

<div class="ex" id="ExTransStartMenu">
<p><a href="#ExTransStartMenu">#3</a>: Makes the classic Start Menu transparent (to additionally make the Start Menu's submenus transparent, see <a href="#ExTransMenu">example #4</a>):</p>
<pre>DetectHiddenWindows, On
WinSet, Transparent, 150, ahk_class BaseBar</pre>
</div>

<div class="ex" id="ExTransMenu">
<p><a href="#ExTransMenu">#4</a>: To make all or selected menus on the entire system transparent, keep a script such as the following always running. Note that although such a script cannot make its own menus transparent, it can make those of other scripts transparent:</p>
<pre>#Persistent
SetTimer, WatchForMenu, 5
return  <em>; End of auto-execute section.</em>

WatchForMenu:
DetectHiddenWindows, On  <em>; Might allow detection of menu sooner.</em>
if WinExist("ahk_class #32768")
    WinSet, Transparent, 150  <em>; Uses the window found by the above line.</em>
return</pre>
</div>

<div class="ex" id="ExRegion">
<p><a href="#ExRegion">#5</a>: Various examples for the <a href="#Region">Region</a> sub-command:</p>
<pre>WinSet, Region, 50-0 W200 H250, ahk_class Notepad  <em>; Make all parts of Notepad outside this rectangle invisible.</em>
WinSet, Region, 50-0 W200 H250 R40-40, ahk_class Notepad  <em>; Same as above but with corners rounded to 40x40.</em>
WinSet, Region, 50-0 W200 H250 E, ahk_class Notepad  <em>; An ellipse instead of a rectangle.</em>
WinSet, Region, 50-0 250-0 150-250, ahk_class Notepad  <em>; A triangle with apex pointing down.</em>
WinSet, Region,, ahk_class Notepad <em>; Restore the window to its original/default display area.</em></pre>
</div>

<div class="ex" id="ExRegionAdvanced">
<p><a href="#ExRegionAdvanced">#6</a>: Here is a region with a more complex area. It creates a see-through rectangular hole inside Notepad (or any other window). There are two rectangles specified below: an outer and an inner. Each rectangle consists of 5 pairs of X/Y coordinates because the first pair is repeated at the end to &quot;close off&quot; each rectangle:</p>
<pre>WinSet, Region, 0-0 300-0 300-300 0-300 0-0   100-100 200-100 200-200 100-200 100-100, ahk_class Notepad</pre>
</div>

</body>
</html>
